<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Opening and Closing the Class Catalog</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Collections Tutorial" />
    <link rel="up" href="BasicProgram.html" title="Chapter 2.  The Basic Program" />
    <link rel="prev" href="opendbenvironment.html" title="Opening and Closing the Database Environment" />
    <link rel="next" href="opendatabases.html" title="Opening and Closing Databases" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 11.2.5.3</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">
		Opening and Closing the Class Catalog
	</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="opendbenvironment.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 2. 
		The Basic Program
	</th>
          <td width="20%" align="right"> <a accesskey="n" href="opendatabases.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="openclasscatalog"></a>
		Opening and Closing the Class Catalog
	</h2>
          </div>
        </div>
      </div>
      <p>
    This section describes how to open and close the Java class
	catalog. The class catalog is a specialized database store that
	contains the Java class descriptions of the serialized objects that
	are stored in the database. The class descriptions are stored in
	the catalog rather than storing them redundantly in each database
	record. A single class catalog per environment must be opened
	whenever serialized objects will be stored in the database.
</p>
      <p>
    The <code class="classname">SampleDatabase</code> class is extended to open and close
	the class catalog. The following additional imports and class
	members are needed.
</p>
      <a id="cb_java_sampledatabase1"></a>
      <pre class="programlisting"><strong class="userinput"><code>import com.sleepycat.bind.serial.StoredClassCatalog;
import com.sleepycat.bind.serial.ClassCatalog;
import com.sleepycat.db.Database;
import com.sleepycat.db.DatabaseConfig;
import com.sleepycat.db.DatabaseType;</code></strong>
import com.sleepycat.db.DatabaseException;
import com.sleepycat.db.Environment;
import com.sleepycat.db.EnvironmentConfig;
import java.io.File;
import java.io.FileNotFoundException;

...

public class SampleDatabase
{
    private Environment env;
<strong class="userinput"><code>    private static final String CLASS_CATALOG = "java_class_catalog";</code></strong>
    ...
<strong class="userinput"><code>    private StoredClassCatalog javaCatalog;</code></strong>
    ...
} </pre>
      <p>
    While the class catalog is itself a database, it contains
	metadata for other databases and is therefore treated specially by
	the DB Java Collections API. The 
    <a class="ulink" href="../../java/com/sleepycat/bind/serial/StoredClassCatalog.html" target="_top">StoredClassCatalog</a>
    
	class encapsulates the catalog store and implements this special
	behavior.
</p>
      <p>
    The following statements open the class catalog by creating a
	<code class="classname">Database</code> and a <code class="classname">StoredClassCatalog</code> object. The catalog
	database is created if it does not already exist.
</p>
      <a id="cb_java_sampledatabase2"></a>
      <pre class="programlisting">    public SampleDatabase(String homeDirectory)
        throws DatabaseException, FileNotFoundException
    {
        ...
<strong class="userinput"><code>        DatabaseConfig dbConfig = new DatabaseConfig();
        dbConfig.setTransactional(true);
        dbConfig.setAllowCreate(true);
        dbConfig.setType(DatabaseType.BTREE);

        Database catalogDb = env.openDatabase(null, CLASS_CATALOG, null, 
                                              dbConfig);

        javaCatalog = new StoredClassCatalog(catalogDb);</code></strong>
        ...
    }
    ...
<strong class="userinput"><code>    public final StoredClassCatalog getClassCatalog() {
        return javaCatalog;
    }</code></strong> </pre>
      <p>
    The 
    
    <a class="ulink" href="../../java/com/sleepycat/db/DatabaseConfig.html" target="_top">DatabaseConfig</a>
    
	class is used to specify configuration parameters when opening a
	database. The first configuration option specified —
	<code class="methodname">setTransactional()</code> — is set to true to create a transactional
	database. While non-transactional databases can also be created,
	the examples in this tutorial use transactional databases.
</p>
      <p>
    <code class="methodname">setAllowCreate()</code> is set to true to specify
	that the database will be created if it does not already exist. If
	this parameter is not specified, an exception will be thrown if the
	database does not already exist.
</p>
      <p>
    <code class="methodname">setDatabaseType()</code> identifies the database storage
    type or access method. For opening a catalog database, the
    <code class="literal">BTREE</code> type is required. <code class="literal">BTREE</code> is the
    most commonly used database type and in this tutorial is used for all
    databases.
</p>
      <p>
    The first parameter of the <code class="methodname">openDatabase()</code> method is an
	optional transaction that is used for creating a new database. If
	null is passed, auto-commit is used when creating a database.
</p>
      <p>
   The second and third parameters of <code class="methodname">openDatabase()</code>
   specify the filename and database (sub-file) name of the database. The
   database name is optional and is <code class="literal">null</code> in this example.
</p>
      <p>
    The last parameter of <code class="methodname">openDatabase()</code> specifies the database
	configuration object.
</p>
      <p>
    Lastly, the <code class="classname">StoredClassCatalog</code> object is created to manage the
	information in the class catalog database. The
	<code class="classname">StoredClassCatalog</code> object will be used in the sections
	following for creating serial bindings.
</p>
      <p>
    The <code class="methodname">getClassCatalog</code> method returns the catalog object for
	use by other classes in the example program.
</p>
      <p>
    When the environment is closed, the class catalog is closed
	also.
</p>
      <a id="cb_close1"></a>
      <pre class="programlisting">    public void close()
        throws DatabaseException
    {
<strong class="userinput"><code>        javaCatalog.close();</code></strong>
        env.close();
    } </pre>
      <p>
    The <code class="methodname">StoredClassCatalog.close()</code> method simply closes the
	underlying class catalog database and in fact the 
    
    <a class="ulink" href="../../java/com/sleepycat/db/Database.html#close()" target="_top">Database.close()</a>
    
	method may be called instead, if desired. It is recommended that you close the catalog database and
	all other databases, before closing the
	environment.
</p>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="opendbenvironment.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="BasicProgram.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="opendatabases.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">
		Opening and Closing the Database Environment
	 </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> 
		Opening and Closing Databases
	</td>
        </tr>
      </table>
    </div>
  </body>
</html>
